fb-watchman

What is fb-watchman?

The fb-watchman npm package is a file watching service developed by Facebook that provides a subscription-based API for monitoring file changes. It is designed to be efficient and scales well for large file systems, making it suitable for applications that need to keep track of changes in the file system in real-time.

What are fb-watchman's main functionalities?

Subscribe to file changes

This code sample demonstrates how to use fb-watchman to subscribe to changes in JavaScript files within a specified project directory. It sets up a watch, creates a subscription, and logs any changes to the console.

const watchman = require('fb-watchman');
const client = new watchman.Client();
client.capabilityCheck({optional:[], required:['relative_root']}, function(error, resp) {
  if (error) {
    console.error(error);
    client.end();
    return;
  }
  // Initiate the watch
  client.command(['watch-project', '/path/to/project'], function(error, resp) {
    if (error) {
      console.error('Error initiating watch:', error);
      return;
    }
    // Create a subscription
    client.command(['subscribe', resp.watch, 'mysubscription', {
      expression: ['allof', ['match', '*.js']],
      fields: ['name', 'size', 'mtime_ms', 'exists', 'type']
    }], function(error, resp) {
      if (error) {
        console.error('Error creating subscription:', error);
        return;
      }
      console.log('Subscription established', resp.subscribe);
    });
  });
});
client.on('subscription', function(resp) {
  if (resp.subscription === 'mysubscription') {
    console.log('File changed:', resp);
  }
});

Other packages similar to fb-watchman

chokidar

Chokidar is a file watching library that provides an API to watch for file system changes. It is built on top of Node.js's native fs module and is known for its stability and cross-platform support. Chokidar is often used as an alternative to fb-watchman for projects that do not require the scalability offered by fb-watchman or when a simpler API is preferred.

gaze

Gaze is another file watching library that allows users to watch files and directories for changes. It provides a simple API and is capable of handling multiple files and directories at once. Gaze is less popular than chokidar and fb-watchman and may not be as efficient for very large file systems.

nodewatch

Nodewatch is a lesser-known file watching library that can be used to monitor file system changes. It is not as widely adopted as fb-watchman or chokidar and may lack some of the advanced features and optimizations present in those libraries.

README

fb-watchman

fb-watchman is a filesystem watcher that uses the Watchman file watching service from Facebook.

Watchman provides file change notification services using very efficient recursive watches and also allows more advanced change matching and filesystem tree querying operations using a powerful expression syntax.

Install

You should install Watchman to make the most of this module.

Then simply:

$ npm install fb-watchman

Key Concepts

• Watchman recursively watches directories.
• Each watched directory is called a root.
• You must initiate a watch on a root using the watch-project command prior to subscribing to changes
• Rather than separately watching many sibling directories, watch-project consolidates and re-uses existing watches relative to a project root (the location of your .watchmanconfig or source control repository root)
• change notifications are relative to the project root

How do I use it?

Read the NodeJS watchman documentation